<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>TrekBuddy Atlas Creator - Readme</title>
<style type="text/css">
body {
	margin-left: 10px;
}

h1,h2,h3 {
	color: #0000CC;
	font-style: italic;
	font-family: Helvetica, Arial, sans-serif;
}

h2 {
	margin-left: 20px;
}

h3 {
	margin-left: 70px;
}

h1 {
	border-bottom: solid thin black;
}

pre {
	margin-left: 140px;
}

p,li {
	font-size: 110%;
	font-family: Helvetica, Arial, sans-serif;
	margin-left: 100px;
}
</style>
</head>
<body>
<h1>TrekBuddy Atlas Creator - Readme</h1>
<p>This is the readme file for the TrekBuddy Atlas Creator (TAC)
application. <br>
TAC is an open source project hosted on SourceForge.net: <br>
<a href="http://trekbuddyatlasc.sourceforge.net">http://trekbuddyatlasc.sourceforge.net</a>
</p>

<h2>License</h2>
<p>TrekBuddy Atlas Creator (TAC) is under GNU General Public License
Version 2 (GPL). For details on the GPL see the license file <a
	href="gpl.txt">gpl.txt</a></p>

<h2>Description</h2>
<p>This application creates atlases for the J2ME application <a
	href="http://www.trekbuddy.net">TrekBuddy</a></p>

<h2>Requirements</h2>
<p>This application requires that a Java Runtime Environment version
6 (v1.6) or higher is installed on the computer.</p>
<p>For reducing the color depth of downloaded tiles the library
files of the "Java Advanced Imaging" (JAI) have to be present on the
system respectively in the same directory as
TrekBuddy_Atlas_Creator.jar. Ready to use binary builds of the Java
Advanced Imaging library can be obtained at <a
	href="https://jai.dev.java.net/binary-builds.html">https://jai.dev.java.net/binary-builds.html</a>
</p>

<h2>Installation</h2>
<p>Copy or move the unzipped files to a folder where you would like
to have TAC installed.</p>

<h2>Application start</h2>
<p>The application is started by executing the <tt>start.cmd</tt> in
a Windows environment or the <tt>start.sh</tt> under an Linux / Unix
environment. At the first application start all necessary files and
folders are automatically created by the application.</p>

<h2>Creating and using atlases with TrekBuddy</h2>
<p>For creating atlases compatible with TrekBuddy you have to select
<b>TrekBuddy tared atlas</b> or <b>TrekBuddy untared atlas</b> as format
in section <b>Atlas settings</b> on the left side of the main window.</p>
<p>After defining the maps and layers for the atlas to be created
start atlas download and creation via the button <b>Create Atlas</b>.
Once atlas download and creation has completed all necessary files
belonging to the atlas can be found in the directory <tt>atlases\[atlas
name]_[current date and time]</tt>.</p>
<p>The atlas itself consists of the the atlas startup file <tt>cr.tar</tt>
(tar format) or <tt>cr.tba</tt> (regular/untared format) and the
subdirectories containing the different maps of the atlas. For using the
atlas with TrekBuddy copy the whole directory onto your J2ME device and
open <tt>cr.tar</tt>/<tt>cr.tba</tt> (in the atlas root directory) in
TrekBuddy as atlas.</p>

<h2>Creating and using atlases with AndNav</h2>
<p>For creating atlases compatible with AndNav you have to select <b>AndNav
atlas format</b> as format in section <b>Atlas settings</b> on the left side
of the main window. <br>
As atlases for AndNav does not support all features provided by
TrekBuddy the following settings are ignored when creating atlases for
AndNav:</p>
<ul>
	<li>Recreate/adjust map tiles (custom tile size and image format)</li>
	<li>Name of all layers and maps</li>
	<li>Structure of the atlas (which maps belongs to which layer)</li>
</ul>

<h2>Creating and using atlases with OziExplorer / large PNG image
export</h2>
<p>For creating atlases compatible with OziExplorer you have to
select <b>OziExplorer (PNG & MAP)</b> as format in section <b>Atlas
settings</b> on the left side of the main window.</p>
<p>As OziExplorer does only support individual maps some features
are ignored when creating atlases in this format:</p>
<ul>
	<li>Recreate/adjust map tiles (custom tile size and image format)</li>
</ul>
<p>The output format of an "atlas" for OziExplorer is one
subdirectory per layer and within this subdirectory one <tt>PNG</tt>
image and one <tt>MAP</tt> file per defined map. For opening a map in
OziExplorer select the menu <b>File</b> &rarr; <b>Load from File</b>
&rarr; <b>Load from MAP file</b> , browse to the layer directory of the
created atlas and select the MAP file.</p>
<p>If you are only interested in the map image you can safely delete
the created map file.</p>
<h3>Warning</h3>
<p>TrekBuddy Atlas Creator uses an highly sophisticated and
optimized algorithm for creating the PNG files for OziExplorer use. This
algorithm allows to create very large maps images at low memory usage.
OziExplorer and most image viewers do not use such sophisticated
algorithms which can lead to the situation that you can create very
large map images - but OziExplorer and other image viewers are not able
to open the image.</p>

<h2>Enhancement requests</h2>
<p>If you are missing the map provider of your choice or have other
enhancement ideas for TrekBuddy Atlas Creator feel free te open an <a
	href="http://sourceforge.net/tracker/?group_id=238075&amp;atid=1105497">Feature
Request Ticket</a> at SourceForge.</p>

<h2>Problems, Bugs &amp; Errors</h2>
<p>In case of unexpected errors while executing TrekBuddy Atlas
Creator you may get presented a exception dialog containing detailed
information about the problem. In such a case please create a new <a
	href="http://sourceforge.net/tracker/?group_id=238075&amp;atid=1105494">ticket
in the Bug Tracker</a> at SourceForge. Please add the detailed exception
information and a detailed description of your last performed actions.</p>

<p>If you do not get such a exception dialog but have other general
problems using TrekBuddy Atlas Creator you can activate the logging
mechanism. To do so download the file <a
	href="https://trekbuddyatlasc.svn.sourceforge.net/svnroot/trekbuddyatlasc/trunk/log4j.xml">log4j.xml</a>
and save it in the directory where the jar file of TrekBuddy Atlas
Creator is installed to.</p>
<p>The next start TrekBuddy Atlas Creator will create a log file in
the current directory (on Windows this is usually the directory where
the JAR file is located on Linux usually the profile directory). Please
note that the log file is erased on each program start. If you think you
have found a bug please file it in the <a
	href="http://sourceforge.net/tracker/?group_id=238075&amp;atid=1105494">bug
tracker at SourceForge</a>.</p>

<h2>Known problems and limitations</h2>
<h3>New map sources</h3>
<p>TrekBuddy Atlas Creator is limited to map sources that provide
their maps if form of map tiles. Each of that map tiles has to be of
size 256x256 pixels. Additionally the map source has to use the
spherical Mercator projection and the number of tiles forming the world
on each zoom level has to be one of the following values: 2<sup>0</sup>,
2<sup>1</sup>, 2<sup>2</sup> ... 2<sup>21</sup>, 2<sup>22</sup>.<br>
For more details see OpenStreetMap Wiki: <a
	href="http://wiki.openstreetmap.org/wiki/Mercator">Mercator</a>, <a
	href="http://wiki.openstreetmap.org/wiki/Height_and_width_of_a_map">Height
and width of a map</a> and <a
	href="http://wiki.openstreetmap.org/wiki/Zoom_levels">Zoom levels</a></p>

<h2>Details for advanced users</h2>
<h3>Custom map sources</h3>
<p>Custom map sources which uses a similar url scheme as
Google/OpenStreetMap can be added by editing the file <tt>settings.xml</tt>
with an text editor.<br>
The following example shows what have to be added for defining a custom
map source. It defines an additional map Source named "Custom OSM
Mapnik" which shows map tiles identical to the predefined map source
"OpenStreetMap Mapnik".</p>
<pre>
&lt;settings&gt;
    &lt;customMapSources&gt;
        &lt;customMapSource&gt;
            &lt;name&gt;Custom OSM Mapnik&lt;/name&gt;
            &lt;minZoom&gt;0&lt;/minZoom&gt;
            &lt;maxZoom&gt;18&lt;/maxZoom&gt;
            &lt;tileType&gt;png&lt;/tileType&gt;
            &lt;tileUpdate&gt;None&lt;/tileUpdate&gt;
            &lt;url&gt;http://tile.openstreetmap.org/{$z}/{$x}/{$y}.png&lt;/url&gt;
        &lt;/customMapSource&gt;
    &lt;/customMapSources&gt;
    ...
&lt;/settings&gt;</pre>
<p>The most important part of this definition is the url. It is a
template containing specific placeholders which are encapsulated by
curly brace:</p>
<ul>
	<li><b>{$z}</b> for the zoom level - number range: [<i>minZoom</i>
	.. <i>maxZoom</i>]</li>
	<li><b>{$x}</b> for the x tile coordinate - number range: [0..2<sup><i>zoom
	level</i></sup>]</li>
	<li><b>{$y}</b> for the y tile coordinate - number range: [0..2<sup><i>zoom
	level</i></sup>]</li>
</ul>
</body>
</html>